# 经典项目案例

```{admonition} 本文引用的文件
:class: note

- [docs/docs/zh_CN/classic/index.rst](../../../products/mpython/classic/index.rst)
- [docs/docs/zh_CN/classic/breathing_light.rst](../../../products/mpython/classic/breathing_light.rst)
- [docs/docs/zh_CN/classic/musicbox.rst](../../../products/mpython/classic/musicbox.rst)
- [docs/docs/zh_CN/classic/lux&sound_Cal.rst](../../../products/mpython/classic/lux&sound_Cal.rst)
- [docs/docs/zh_CN/classic/dht11.rst](../../../products/mpython/classic/dht11.rst)
- [docs/docs/zh_CN/classic/servo.rst](../../../products/mpython/classic/servo.rst)
- [docs/docs/zh_CN/classic/clock.rst](../../../products/mpython/classic/clock.rst)
- [docs/docs/zh_CN/classic/weather.rst](../../../products/mpython/classic/weather.rst)
- [docs/docs/zh_CN/classic/game/index.rst](../../../products/mpython/classic/game/index.rst)
- `docs/examples/pin/breathing_light.py`
- `docs/examples/board_inside/PlayMusic.py`
- `docs/examples/network/时钟/DigitalClock.py`
- `docs/examples/game/snake.py`
- `docs/examples/game/tetris.py`
```

## 产品概述
本项目围绕 mPython 掌控板（ESP32 双核 MicroPython）提供一系列面向 K12 创客教育的经典实战案例，覆盖基础 IO、传感器、音频、网络与游戏等主题。通过“呼吸灯、音乐盒、照度计、温湿度、舵机、时钟、气象站、物联网、游戏”等案例，帮助学习者从入门到进阶，掌握硬件驱动、数据读取、UI 显示、网络通信与简单算法的综合能力。

- 目标用户：K12 学生、创客教师、初学者开发者
- 核心价值：以可运行的示例代码串联底层驱动与上层应用，强调“所见即所得”的学习体验
- 适用场景：课堂实验、课后拓展、竞赛训练、家庭创客实践

## 核心业务流程
以下流程展示了典型项目的端到端链路：输入感知 → 数据处理 → 输出呈现/控制 → 可选联网或交互。

```text
flowchart TD
A["上电启动"] --> B["初始化模块<br/>OLED/按键/传感器/网络"]
B --> C{"是否联网?"}
C -- 否 --> D["本地循环: 读取传感器/按键"]
C -- 是 --> E["连接WiFi并获取时间/天气"]
E --> F["解析JSON/时间数据"]
D --> G["映射/滤波/阈值判断"]
F --> G
G --> H["更新UI/播放声音/驱动舵机/LED"]
H --> I{"事件触发?"}
I -- 是 --> J["中断/回调处理"]
I -- 否 --> D
J --> D
```

该流程贯穿呼吸灯、音乐盒、照度计、温湿度、舵机、时钟、气象站与游戏等案例，体现“感知—计算—执行—反馈”的闭环。

## 功能模块清单
- 呼吸灯
  - 职责：使用 PWM 控制 LED 亮度，实现平滑渐变效果
  - 验收要点：亮度变化连续无闪烁；周期可调；支持开关控制
  - 参考实现：`breathing_light.py`
- 音乐盒
  - 职责：基于内置曲目或自定义音符序列，结合按键切换歌曲
  - 验收要点：按键响应及时；播放/切换稳定；屏幕显示当前曲目索引
  - 参考实现：[musicbox.rst](../../../products/mpython/classic/musicbox.rst)、`PlayMusic.py`
- 照度计/噪声计
  - 职责：读取光线与声音传感器值，映射为百分比并在 UI 展示
  - 验收要点：数值范围合理；条形图刷新流畅；单位标注清晰
  - 参考实现：[lux&sound_Cal.rst](../../../products/mpython/classic/lux&sound_Cal.rst)
- 温湿度（DHT11）
  - 职责：通过单总线读取温湿度，显示在 OLED
  - 验收要点：读数稳定；异常时提示；引脚连接正确
  - 参考实现：[dht11.rst](../../../products/mpython/classic/dht11.rst)
- 舵机
  - 职责：PWM 控制舵机角度，结合加速度计实现倾斜控制
  - 验收要点：角度映射准确；抖动小；安全脉宽范围
  - 参考实现：[servo.rst](../../../products/mpython/classic/servo.rst)
- 时钟（数字/模拟）
  - 职责：联网同步 NTP 时间，定时刷新显示
  - 验收要点：时间同步成功；刷新周期稳定；异常提示友好
  - 参考实现：[clock.rst](../../../products/mpython/classic/clock.rst)、`DigitalClock.py`
- 气象站（网络天气）
  - 职责：调用心知天气 API，解析 JSON 并显示实况与预报
  - 验收要点：API 请求成功；图标/温度/城市显示正确；定时刷新
  - 参考实现：[weather.rst](../../../products/mpython/classic/weather.rst)
- 物联网（OneNET/通用）
  - 职责：将传感器数据上报至云平台，或接收云端指令
  - 验收要点：连接稳定；数据格式正确；断线重连机制
  - 参考入口：[oneNET/index.rst](../../../products/mpython/classic/oneNET/index.rst)
- 游戏（贪吃蛇/俄罗斯方块/Pong/Flappy Bird）
  - 职责：利用按键/触摸/加速度计进行交互，渲染帧动画
  - 验收要点：帧率稳定；碰撞检测准确；状态切换清晰
  - 参考实现：[game/index.rst](../../../products/mpython/classic/game/index.rst)、`snake.py`、`tetris.py`

**章节来源**
- [docs/docs/zh_CN/classic/index.rst:1-18](../../../products/mpython/classic/index.rst)
- [docs/docs/zh_CN/classic/breathing_light.rst:1-8](../../../products/mpython/classic/breathing_light.rst)
- [docs/docs/zh_CN/classic/musicbox.rst:1-48](../../../products/mpython/classic/musicbox.rst)
- [docs/docs/zh_CN/classic/lux&sound_Cal.rst:1-23](../../../products/mpython/classic/lux&sound_Cal.rst)
- [docs/docs/zh_CN/classic/dht11.rst:1-58](../../../products/mpython/classic/dht11.rst)
- [docs/docs/zh_CN/classic/servo.rst:1-95](../../../products/mpython/classic/servo.rst)
- [docs/docs/zh_CN/classic/clock.rst:1-144](../../../products/mpython/classic/clock.rst)
- [docs/docs/zh_CN/classic/weather.rst:1-143](../../../products/mpython/classic/weather.rst)
- [docs/docs/zh_CN/classic/game/index.rst:1-25](../../../products/mpython/classic/game/index.rst)

## 数据与状态
- 传感器数据流
  - 光线/声音：ADC 采样 → numberMap 映射 → UI 条形图
  - 温湿度：DHT11 单总线协议 → 温度/湿度整数 → 文本显示
  - 加速度/陀螺仪：六轴传感器 → 角度/角速度 → 舵机角度映射
- 时间与网络数据
  - NTP 时间：ntptime.settime() → time.localtime() → 格式化显示
  - 天气数据：urequests.get → JSON 解析 → 图标/温度/城市 → 定时刷新
- 游戏状态机
  - 贪吃蛇：方向/移动/生长/碰撞/胜负 → 帧循环刷新
  - 俄罗斯方块：块生成/旋转/下落/消行/计分 → 触摸/按键交互
- 关键状态边界
  - 网络连接失败：超时异常捕获并提示
  - 传感器读取失败：重试/默认值/错误提示
  - 游戏结束：分数显示与重置入口

```text
sequenceDiagram
participant U as "用户"
participant M as "主控程序"
participant S as "传感器/外设"
participant N as "网络(NTP/天气)"
participant D as "显示/音频/执行器"
U->>M : 启动/按键/触摸
M->>S : 读取光照/声音/温湿度/加速度
S-->>M : 原始数据
M->>N : 连接WiFi/获取时间/天气
N-->>M : 时间/天气JSON
M->>M : 数据映射/滤波/阈值判断
M->>D : 更新UI/播放声音/驱动舵机/LED
D-->>U : 视觉/听觉反馈
```

**章节来源**
- `docs/examples/pin/breathing_light.py:1-26`
- `docs/examples/board_inside/PlayMusic.py:1-29`
- `docs/examples/network/时钟/DigitalClock.py:1-34`
- `docs/examples/game/snake.py:1-230`
- `docs/examples/game/tetris.py:1-261`

## 关键约束与边界
- 硬件与引脚
  - 特定引脚不可用作通用 IO（如 P4 用于光线传感器、P10 用于声音传感器）
  - 舵机脉宽范围因型号而异，需根据实际器件调整最小/最大脉宽
- 网络与环境
  - WiFi 连接与 NTP/天气 API 依赖外部网络，需考虑超时与重试
  - 天气服务需要有效的 API Key，且遵循其速率限制与参数规范
- 性能与功耗
  - 高频刷新（UI/音频/舵机）可能增加功耗与发热，需合理设置刷新周期
  - 游戏帧率需平衡流畅性与资源占用
- 可靠性与容错
  - 传感器读取失败应降级处理（默认值/提示）
  - 网络异常需捕获并给出明确提示，避免程序崩溃
- 扩展性
  - 模块化设计便于替换传感器/平台（如 ESP32 与 ESP32-S3 的差异）
  - 统一的数据映射与 UI 接口降低耦合度

**章节来源**
- [docs/docs/zh_CN/classic/servo.rst:35-84](../../../products/mpython/classic/servo.rst)
- [docs/docs/zh_CN/classic/clock.rst:18-65](../../../products/mpython/classic/clock.rst)
- [docs/docs/zh_CN/classic/weather.rst:13-72](../../../products/mpython/classic/weather.rst)
- `docs/examples/game/snake.py:178-230`
- `docs/examples/game/tetris.py:210-261`